Software Requirements Specification (SRS)

AquaX — Shrimp Farming Management Platform

Document Info
Version	1.0
Status	Draft — Software Baseline + Current Implementation Alignment
Created Date	2026-09-16
Last Updated	2026-09-16
Owner	Product & Engineering
Reviewers	QA, Architecture, Security, Operations
Source Documents	`01_PRD — Product Requirements Document.md`, `02_BRD — Business Requirements Document.md`, `01-product/SRS.md`, `01-product/requirements/*`, `reference/product/SRS.md`

Implementation alignment note: This SRS preserves target software requirements even when implementation is not complete. Status values are CONFIRMED, PARTIAL, PLANNED, FUTURE and TBD.

Introduction
System Overview
Users And Roles
Functional Requirements
Data Requirements
Permission Matrix
Business Rules
Integration Requirements
AI Requirements
Non-Functional Requirements
Business Flows
MVP Scope Mapping
Acceptance Criteria
Assumptions, Dependencies And Constraints
Open Questions
Suggested Screen List
Traceability
Approval
Document History

1. Introduction

1.1 Purpose

This Software Requirements Specification defines the software-level requirements for AquaX, a SaaS/IoT shrimp farming management platform. It translates business needs from the BRD and product direction from the PRD into functional, data, permission, integration, non-functional and acceptance requirements that engineering and QA can use for implementation and validation.

This document does not replace detailed API contracts, database schema, UI wireframes, AI model design or deployment runbooks. Those are maintained in the 10-part documentation tree.

1.2 Scope

AquaX covers:

web and mobile applications;
authentication, user, role and operational scope management;
farm, pond and crop management;
water monitoring and sensor history;
alert, notification and ticket workflows;
IoT telemetry ingestion and device control;
feeding, farming logs, productivity and reports;
Farming Handbook;
AI chatbot, image analysis, recommendation and prediction capabilities by phase;
system configuration for thresholds, automation, SLA, notification and AI policy.

1.3 Requirement Code Convention

Code Family	Meaning
`FR-*`	Functional requirement.
`DATA-*`	Logical data requirement.
`BR-*`	Business rule.
`INT-*`	Integration requirement.
`NFR-*`	Non-functional requirement.
`AC-*`	Acceptance criterion.
`AI-*`	AI capability requirement.
`AIP-*`	AI prediction requirement.

2. System Overview

2.1 Product Context

AquaX centralizes shrimp farming operations around farms, ponds and crop cycles. The primary operational hub is pond context: water metrics, sensor status, device state, feeding, farming logs, alerts, tickets, reports, handbook references and AI support.

2.2 Logical Components

Component	Responsibility	Current Status
Web Frontend	Admin/operator dashboard, management screens, reports and configuration.	CONFIRMED / PARTIAL
Mobile App	Field workflows, role-based tabs, quick entry, incidents and notifications.	CONFIRMED / PARTIAL
Backend API	Auth, RBAC/scope, business modules, reports, IoT ingest and integrations.	CONFIRMED / PARTIAL
Database	PostgreSQL/TimescaleDB data store for business data and telemetry.	CONFIRMED
Redis	Cache/session runtime support.	CONFIRMED
IoT Ingestion	MQTT, Telegraf and worker-based telemetry ingestion.	PARTIAL
Device Control	Command dispatch, ACK/timeout and command history.	PARTIAL
Notification Service	In-app, push and email event delivery.	PARTIAL
Reporting Service	Online reports, Excel export and scheduled reports.	PARTIAL / PLANNED
AI Service	Chatbot, image analysis, recommendations and predictions.	PLANNED
Object Storage	Ticket media, chatbot images and report files.	PARTIAL

2.3 Current Implementation Summary

The codebase contains a working foundation across backend, web, mobile and IoT. Many modules are partial: authorization scope has known temporary bypasses, several web/mobile feature screens are placeholders, scheduled reports are not implemented, and production AI/prediction services are not implemented.

3. Users And Roles

Role	Description	Data Scope	Main Permissions	Current Status
Admin	System administrator.	System-wide.	Users, farms, ponds, devices, sensors, settings, reports and handbook administration.	PARTIAL
Farm Owner	Farm owner/operator.	Own farm and ponds.	Dashboard, assignments, logs, device actions if enabled, reports, tickets, handbook and AI usage.	PARTIAL
Pond Technician	Field technician.	Assigned ponds.	Operational data entry, alerts, device action if enabled, tickets, handbook and AI usage.	PARTIAL
Admin Technical Staff	Central support technician.	Assigned tickets/incidents and related pond context.	Ticket processing, technical notes, closure and support diagnostics.	PARTIAL
Viewer / Owner-facing User	Read-oriented user.	Assigned farm/pond context.	Overview, activity, reports where enabled.	PARTIAL

4. Functional Requirements

4.1 MOD-01 — Authentication And User Management

ID	Requirement	Priority	Acceptance Summary	Status
FR-01-001	Users can log in with valid email and password.	Must	User lands on role-appropriate dashboard.	PARTIAL
FR-01-002	Users can log out of current session and all devices where supported.	Must	Tokens/sessions are invalidated.	PARTIAL
FR-01-003	Users can request password reset by email.	Must	Reset link expires by policy/configuration.	PARTIAL
FR-01-004	Admin can create, edit, disable users and assign roles.	Must	Disabled users cannot log in; history remains.	PARTIAL
FR-01-005	Admin can assign farm/pond/ticket scope.	Must	Users only see assigned data.	PARTIAL
FR-01-006	Farm owner can create/assign pond technicians if permitted.	Should	Assigned technicians see only assigned ponds.	PARTIAL
FR-01-007	System enforces session timeout.	Must	Inactive users must re-authenticate.	PARTIAL
FR-01-008	User and permission changes are audited.	Must	Actor, time, action and before/after are traceable where implemented.	PARTIAL

4.2 MOD-02 — Farm / Pond / Crop Management

ID	Requirement	Priority	Acceptance Summary	Status
FR-02-001	Admin can create, view, edit and close farms.	Must	Farm has name, owner, address, region and status.	PARTIAL
FR-02-002	Users with permission can create, view and edit ponds.	Must	Pond includes code, area, type, stocking date, shrimp count, density and size.	PARTIAL
FR-02-003	System manages crop cycles by pond.	Must	One active crop per pond at a time.	PARTIAL
FR-02-004	System supports pond technician assignment.	Must	Assigned KTV sees assigned ponds only.	PARTIAL
FR-02-005	Admin can assign sensors and IoT devices to ponds.	Must	Assigned devices/sensors appear in pond context.	PARTIAL
FR-02-006	System displays pond list with overview status.	Must	Status reflects alert/sensor/device context.	PARTIAL
FR-02-007	Closed crop operation data is read-only except privileged override.	Should	Special changes are audited.	PARTIAL

4.3 MOD-03 — Water Monitoring Dashboard

ID	Requirement	Priority	Acceptance Summary	Status
FR-03-001	System displays farm dashboard with ponds and alert status.	Must	User sees only scoped ponds.	PARTIAL
FR-03-002	Pond dashboard shows pH, DO, salinity, algae/ORP, alkalinity and temperature.	Must	Value, unit, measured time and color status shown.	PARTIAL
FR-03-003	Time-series charts support 24h, 7d, 30d and custom ranges.	Must	Charts match selected range.	PARTIAL
FR-03-004	Safe thresholds and threshold breaches are visible.	Should	Breaches are highlighted and link to alerts where available.	PARTIAL
FR-03-005	Sensor online/offline/error status is shown.	Must	Offline sensors can trigger alert.	PARTIAL
FR-03-006	Sensor history can be filtered by pond, metric and time.	Must	User sees scoped data only.	PARTIAL
FR-03-007	Pond crop context appears beside water metrics.	Should	Day of culture, area, density and shrimp size are visible.	PARTIAL

4.4 MOD-04 — Alert Management

ID	Requirement	Priority	Acceptance Summary	Status
FR-04-001	System creates alerts when water metrics exceed thresholds.	Must	Alert records pond, metric, value, threshold, time and severity.	PARTIAL
FR-04-002	System creates sensor/device connectivity alerts.	Must	Alert routes to correct recipients.	PARTIAL
FR-04-003	Alert list supports filters by type, severity, pond, farm, status and time.	Must	Results respect user scope.	PARTIAL
FR-04-004	Alerts follow lifecycle New, Accepted, In Progress and Closed.	Must	Status change records actor/time/note.	PARTIAL
FR-04-005	Assigned users can acknowledge alerts.	Must	Related users see updated status.	PARTIAL
FR-04-006	Overdue alerts can escalate.	Should	Escalation follows configured SLA/T1/T2.	PARTIAL
FR-04-007	System suggests handling steps from rule/AI by phase.	Should	Suggestion appears in alert detail when configured.	PARTIAL / PLANNED

4.5 MOD-05 — IoT Device Control

ID	Requirement	Priority	Acceptance Summary	Status
FR-05-001	Device list shows pond devices, type, status, mode and connection.	Must	List respects user scope.	PARTIAL
FR-05-002	Authorized users can turn devices on/off from web or mobile.	Must	Command status is success, failed or pending.	PARTIAL
FR-05-003	System stores command history.	Must	Command log includes device, command, user, request time, result and response.	PARTIAL
FR-05-004	Device mode can switch between manual and auto.	Should	Current mode is clear in UI.	PARTIAL
FR-05-005	Automatic rules can use DO, temperature, schedule or alert thresholds.	Should	Rules are active only when auto mode is enabled.	PARTIAL
FR-05-006	Device non-response creates timeout/error alert.	Must	Alert links to command log.	PARTIAL
FR-05-007	Auto mode must not override recent manual command for configured Y minutes.	Should	Y is configurable.	PLANNED / PARTIAL

4.6 MOD-06 — Feeding Management And AI Suggestion

ID	Requirement	Priority	Acceptance Summary	Status
FR-06-001	Users can enter feeding by session.	Must	Record includes feed type, amount, time, user and note.	PARTIAL
FR-06-002	Users can record feeding reaction.	Should	Reaction supports later history and suggestions.	PARTIAL
FR-06-003	Feeding history is available by day, week and crop.	Must	Totals visible by pond/farm.	PARTIAL
FR-06-004	System suggests daily feed amount.	Should	Shows inputs, recommendation and confidence if AI.	PLANNED
FR-06-005	System suggests per-session amount and optimal feeding time.	Could	Adjusts by environment/history where available.	PLANNED
FR-06-006	System warns when DO/pH is unsafe for feeding.	Must	Warning appears during feeding entry and notification if severe.	PARTIAL
FR-06-007	System calculates PCR/FCR after approved formulas.	Should	UI shows not configured if formula unavailable.	PLANNED
FR-06-008	Users can override suggestion and store reason where needed.	Must	Suggestion and actual value are preserved.	PARTIAL

4.7 MOD-07 — Productivity And Farming Logs

ID	Requirement	Priority	Acceptance Summary	Status
FR-07-001	Users can enter manual pH, alkalinity and environment values.	Must	Record includes user, pond, crop and date.	PARTIAL
FR-07-002	Users can enter mineral records.	Must	Mineral catalog is configurable.	PARTIAL
FR-07-003	Users can enter siphon records.	Must	Unit and bottom condition are captured where configured.	PARTIAL
FR-07-004	Users can enter productivity records.	Should	Productivity rule requires domain confirmation.	PARTIAL
FR-07-005	Logs are visible by day, week and crop.	Must	Filters include farm, pond, type and time.	PARTIAL
FR-07-006	Same-day edits are allowed before finalization.	Should	Post-finalization changes require privilege and audit.	PARTIAL
FR-07-007	System summarizes productivity by pond/day/crop.	Should	Summary appears in reports/dashboard where data exists.	PARTIAL

4.8 MOD-08 — Reports And Excel Export

ID	Requirement	Priority	Acceptance Summary	Status
FR-08-001	Water monitoring report is available.	Must	Includes tables, charts and threshold breach count.	PARTIAL
FR-08-002	Device report is available.	Must	Includes runtime, command history and errors.	PARTIAL
FR-08-003	Feeding report is available.	Must	Includes totals and PCR/FCR when configured.	PARTIAL
FR-08-004	Farming operation report is available.	Must	Includes manual environment, minerals and siphon.	PARTIAL
FR-08-005	Productivity report is available.	Should	Shows valid productivity data only.	PARTIAL
FR-08-006	Ticket report is available.	Should	Supports SLA and status filters.	PARTIAL
FR-08-007	Handbook/chatbot usage report is available.	Could	Requires handbook/chatbot usage data.	PLANNED
FR-08-008	Reports can export Excel by user scope.	Must	File does not contain unauthorized data.	PARTIAL
FR-08-009	Weekly report email can be scheduled.	Could	Email sends to configured recipients.	PLANNED

4.9 MOD-09 — Incident / Ticket Management

ID	Requirement	Priority	Acceptance Summary	Status
FR-09-001	Farm owners/KTV can create technical tickets.	Must	Ticket includes pond, device if any, description, severity and attachments.	PARTIAL
FR-09-002	Tickets support photo/video attachment.	Should	File is stored securely and visible in ticket detail.	PARTIAL
FR-09-003	Ticket list supports filters.	Must	Results respect user scope.	PARTIAL
FR-09-004	Admin can assign/reassign support technician.	Must	Assignee receives notification/email.	PARTIAL
FR-09-005	Support technician can accept, update and close ticket.	Must	Updates include timestamp and actor.	PARTIAL
FR-09-006	System tracks response and resolution SLA.	Should	Overdue tickets are highlighted/escalated.	PARTIAL
FR-09-007	Ticket creation sends configured technical email.	Must	Recipients are configurable.	PARTIAL

4.10 MOD-10 — Farming Handbook

ID	Requirement	Priority	Acceptance Summary	Status
FR-10-001	Article library supports farming topics.	Must	Users can browse approved articles.	PARTIAL
FR-10-002	Users can search by keyword.	Must	Search returns permitted visible content.	PARTIAL
FR-10-003	Articles can filter by topic/stage/metric.	Should	Filters can combine conditions.	PARTIAL
FR-10-004	Alert-related articles can appear from alert detail.	Could	Alert links to related content.	PARTIAL
FR-10-005	Users can favorite articles.	Could	Favorites are available in profile/handbook.	PARTIAL
FR-10-006	Admin can create, edit, approve, archive and version articles.	Must	Only approved articles show to users/chatbot.	PARTIAL
FR-10-007	Chatbot-referenced articles are not hard-deleted.	Must	References remain recoverable.	PLANNED / PARTIAL

4.11 MOD-11 — AI Chatbot

ID	Requirement	Priority	Acceptance Summary	Status
FR-11-001	Chatbot UI exists on web and mobile for authorized roles.	Should	User sees chatbot only when permitted.	PLANNED
FR-11-002	Chatbot supports text Q&A.	Should	Answers use approved handbook and permitted pond data.	PLANNED
FR-11-003	User can select pond context.	Should	Context does not exceed data scope.	PLANNED
FR-11-004	User can upload/capture image for preliminary analysis.	Could	Image follows retention policy.	PLANNED
FR-11-005	Chatbot can assemble automatic pond context.	Should	Context used is visible in answer where appropriate.	PLANNED
FR-11-006	Chatbot shows confidence and references.	Should	Source and confidence are visible when available.	PLANNED
FR-11-007	Chatbot suggests KTV/ticket fallback when serious or low-confidence.	Should	User can create ticket from chat.	PLANNED
FR-11-008	Chatbot stores conversation history.	Could	Retention is configurable/TBD.	PLANNED
FR-11-009	User can rate chatbot response.	Could	Feedback supports quality reporting.	PLANNED
FR-11-010	Chatbot cannot answer with unauthorized pond data.	Must	Unauthorized questions are refused without data leak.	PLANNED

4.12 MOD-12 — Notification System

ID	Requirement	Priority	Acceptance Summary	Status
FR-12-001	System creates in-app notification for alerts, tickets, escalation and important updates.	Must	Notification links to target entity.	PARTIAL
FR-12-002	Mobile receives push notifications for important events.	Must	Push opens correct detail if user still has access.	PARTIAL / PLANNED
FR-12-003	System sends email for reset password, tickets, escalation and weekly reports.	Must	Email uses configured recipients/templates where supported.	PARTIAL
FR-12-004	Users can view, filter, mark read or delete notifications.	Should	Read state syncs across web/mobile.	PARTIAL
FR-12-005	Admin can configure recipients, channels and event rules.	Should	New config affects future events.	PARTIAL
FR-12-006	System prevents duplicate notifications for same event within debounce window.	Must	Duplicate behavior follows config.	PLANNED / PARTIAL

4.13 MOD-13 — System Configuration

ID	Requirement	Priority	Acceptance Summary	Status
FR-13-001	Admin can configure alert thresholds by metric and scope.	Must	New threshold applies to future alerts.	PARTIAL
FR-13-002	Admin can configure device automation rules.	Should	Rule has condition, action, scope and enabled state.	PARTIAL
FR-13-003	Admin can manage catalogs for feed, minerals, devices, tickets and alerts.	Must	Catalog values are reused in forms.	PARTIAL
FR-13-004	Admin can configure email templates and recipients.	Should	Template supports variables.	PARTIAL / PLANNED
FR-13-005	Admin can configure ticket/alert SLA.	Should	SLA supports escalation.	PARTIAL
FR-13-006	Admin can configure SaaS plans/account limits if product adopts plans.	Could	Optional if commercial model is not confirmed.	PLANNED
FR-13-007	Admin can configure AI knowledge sources and safety policy.	Should	Chatbot uses only enabled approved sources.	PLANNED

5. Data Requirements

ID	Entity	Key Attributes	Relationship / Usage	Status
DATA-01	User	id, name, email, phone, role, status, assigned scopes, timestamps	Role and operational access.	PARTIAL
DATA-02	Farm	id, name, owner, address, region, status	Has many ponds.	PARTIAL
DATA-03	Pond	id, farm_id, code, area, type, stocking date, shrimp count, density, shrimp size, status	Belongs to farm; has crops, sensors, devices.	PARTIAL
DATA-04	Crop	id, pond_id, start/end date, total_feed, production, pcr_fcr, status, notes	One active crop per pond.	PARTIAL
DATA-05	Sensor	id, pond_id, metric_type, frequency, threshold_config, connection_status	Creates water quality records.	PARTIAL
DATA-06	Water Quality Record	farm, pond, sensor, metric, value, unit, measured_at, source, status	Dashboard, alerting and AI input.	PARTIAL
DATA-07	Device	id, pond_id, name, type, status, mode, connection_status	Has command logs and alerts.	PARTIAL
DATA-08	Device Command Log	device, command, requested_by, requested_at, status, executed_at, response	Device control audit.	PARTIAL
DATA-09	Feeding Record	pond, crop, feed_type, amount, time, user, reaction, suggestion snapshot	Feeding history and AI input.	PARTIAL
DATA-10	Mineral Record	pond, crop, date, mineral_type, amount, unit, user	Farming log.	PARTIAL
DATA-11	Siphon Record	pond, crop, date, morning, afternoon, total, unit, note	Farming log.	PARTIAL
DATA-12	Productivity Record	pond, crop, date, amount, unit, method, user, notes	Productivity reporting/AI.	PARTIAL
DATA-13	Alert	pond, type, severity, source, status, assignee, timestamps	Alert workflow.	PARTIAL
DATA-14	Ticket	pond, device, creator, description, severity, status, assignee, SLA, closed_at	Incident workflow.	PARTIAL
DATA-15	Ticket Attachment	ticket, file_url, type, uploader, uploaded_at	Ticket evidence.	PARTIAL
DATA-16	Handbook Article	title, category, stage, metric, status, version, content, approver	Knowledge and AI source.	PARTIAL
DATA-17	Chatbot Conversation	user, pond, question, image, answer, references, confidence, feedback	AI history.	PLANNED
DATA-18	Notification	user, event_type, channel, title, body, read_status, target_url	Notification center.	PARTIAL
DATA-19	Configuration	config_type, scope, key, value, effective_from, updated_by	Thresholds, SLA, catalogs, email, rules and AI policy.	PARTIAL

5.1 Retention Requirements

Data Type	Minimum Retention	Status
Sensor data	1 year; extendable by customer need.	TBD
Device history and command logs	1 year.	TBD
Feeding, manual environment, mineral and siphon records	Full crop history across multiple crops.	PARTIAL
Alerts, tickets and audit logs	At least 1 year.	TBD
Handbook content	Permanent by version.	PARTIAL
Chatbot conversations and images	At least crop lifecycle; privacy policy TBD.	PLANNED

6. Permission Matrix

Function Group	Admin	Farm Owner	Pond Technician	Admin Technical Staff	Status
Login/profile	Yes	Yes	Yes	Yes	PARTIAL
User management	Full	Create/assign KTV if permitted	No	No	PARTIAL
Farm management	Full	Own farm as permitted	Related farm view	Assigned farm/ticket context	PARTIAL
Pond/crop management	Full	Own ponds/crops	Assigned ponds	Assigned pond/ticket context	PARTIAL
Water dashboard	System-wide	Own farm	Assigned ponds	Assigned context	PARTIAL
Alerts	System-wide	Own farm	Assigned ponds	Assigned alerts/tickets	PARTIAL
Device control	Full	Own farm if enabled	Assigned ponds if enabled	If granted	PARTIAL
Feeding/logs	Full	Own farm	Assigned ponds	Assigned context	PARTIAL
Reports/Excel	System-wide	Own farm	If granted	Assigned context	PARTIAL
Tickets	View/assign/configure SLA	Create/view own farm	Create/view assigned ponds	Accept/process/close assigned	PARTIAL
Handbook	Admin content	Read/favorite	Read/favorite	Read/favorite	PARTIAL
Chatbot	Use/configure policy	Own farm	Assigned ponds	Assigned context	PLANNED
System configuration	Full	Farm-level if granted	No	Technical config if granted	PARTIAL

Backend authorization is mandatory. Web/mobile UI visibility is not sufficient.

7. Business Rules

ID	Rule	Status
BR-01	Each user has one primary role unless explicitly redesigned.	PARTIAL
BR-02	Every protected query/action is filtered by role and scope.	PARTIAL
BR-03	Users cannot view/export/receive/chat about unauthorized data.	PARTIAL
BR-04	Disabled accounts cannot log in but history remains.	PARTIAL
BR-05	Every device command logs requester, time, command, status and response.	PARTIAL
BR-06	Non-responsive devices create timeout/error alert after configured X seconds.	PARTIAL
BR-07	Auto mode does not override manual command for configured Y minutes.	PLANNED / PARTIAL
BR-08	Device control permission follows role, pond/farm scope and system config.	PARTIAL
BR-09	Ticket states include New, Accepted, In Progress and Closed.	PARTIAL
BR-10	Ticket creation notifies configured technical recipients.	PARTIAL
BR-11	Tickets past SLA escalate to Admin/technical supervisor.	PARTIAL
BR-12	Alerts past T1/T2 escalate according to configuration.	PARTIAL
BR-13	Chatbot uses only approved handbook and authorized pond data.	PLANNED
BR-14	Image analysis is preliminary and cannot definitively diagnose disease without technician confirmation.	PLANNED
BR-15	Chatbot answers show source/confidence when possible.	PLANNED
BR-16	AI feeding suggestions are optional recommendations.	PLANNED
BR-17	Low-confidence or serious AI cases suggest KTV/ticket fallback.	PLANNED

8. Integration Requirements

ID	Integration	Requirement	Status
INT-01	Sensor data ingestion	Receive sensor data by push or pull; final production mechanism TBD.	PARTIAL
INT-02	Device control gateway	Send commands and receive execution response.	PARTIAL
INT-03	Email service	Send reset password, ticket, escalation and weekly reports.	PARTIAL
INT-04	Push notification	Mobile receives push for alerts, tickets and important events.	PARTIAL / PLANNED
INT-05	Object storage	Store ticket media, chatbot images and exported report files securely.	PARTIAL
INT-06	AI/LLM service	Provide chatbot, image analysis and recommendations by phase.	PLANNED
INT-07	Future channels	SMS, Zalo and automated calls are future, not MVP.	FUTURE

9. AI Requirements

9.1 AI Capability Requirements

ID	Capability	Requirement	Phase	Status
AI-01	Text chatbot	Answer operational questions from handbook and authorized pond data.	MVP 3	PLANNED
AI-02	Image analysis	Preliminary assessment from shrimp, water, feed tray, pond bottom or device images.	MVP 4	PLANNED
AI-03	Feeding recommendation	Suggest daily/session feed amount and time window.	MVP 4	PLANNED
AI-04	Growth/productivity assessment	Analyze crop, feed, environment and productivity history.	MVP 4	PLANNED
AI-05	Alert recommendation	Detect abnormal situations and recommend response; may begin rule-based.	MVP 2-4	PARTIAL / PLANNED
AI-06	Energy optimization	Suggest device schedules to reduce power use.	MVP 3-4	PLANNED
AI-07	Prediction	Predict water trend, alert risk, feed need, growth, harvest and equipment/energy risk.	MVP 3-4	PLANNED

9.2 AI Prediction Requirements

ID	Prediction Group	Expected Output	Status
AIP-01	Water quality prediction	Trend, risk level, horizon and recommended check/action.	PLANNED
AIP-02	Alert risk prediction	Probability/risk band, likely cause and preventive recommendation.	PLANNED
AIP-03	Shrimp health risk prediction	Risk band, missing data note and technician inspection suggestion.	PLANNED
AIP-04	Feed need prediction	Feed range, confidence, reason and fallback rule.	PLANNED
AIP-05	Growth/productivity prediction	Growth forecast, productivity risk and contributing factors.	PLANNED
AIP-06	Harvest timing prediction	Harvest window, confidence and required validation data.	PLANNED
AIP-07	Device/energy risk prediction	Failure/energy risk, inspection recommendation and schedule suggestion.	PLANNED

9.3 AI Safety Requirements

Control	Requirement	Status
Authorization	AI uses only data user is allowed to access.	PLANNED
References	AI cites approved handbook/data sources where applicable.	PLANNED
Confidence	AI exposes confidence/uncertainty and avoids definitive claims when evidence is weak.	PLANNED
Logging	AI prompts/context metadata/results/references/feedback/escalation are logged by privacy policy.	PLANNED
Human fallback	Serious or low-confidence outputs route to KTV/ticket workflow.	PLANNED
Rule-based fallback	If model unavailable or data insufficient, use rule-based recommendation or no-prediction state.	PLANNED
No dangerous autonomy	AI cannot directly execute device command or critical operation without confirmation and authorization.	PLANNED

10. Non-Functional Requirements

ID	Group	Requirement	Target / Criteria	Status
NFR-01	Performance	Dashboard loads quickly on web/mobile.	Legacy target < 3 seconds under normal data.	TBD
NFR-02	Performance	Sensor API responds quickly.	Legacy target < 1 second under standard load.	TBD
NFR-03	Performance	Excel export completes within acceptable time.	Legacy target < 30 seconds for 1-year single pond/farm, or background job.	TBD
NFR-04	Security	Production uses HTTPS only.	No unencrypted HTTP access.	PARTIAL
NFR-05	Security	RBAC/scope is strictly enforced.	API and UI do not leak cross-scope data.	PARTIAL
NFR-06	Security	Sensitive data is protected.	Password hash, token/session protection and file access control.	PARTIAL
NFR-07	Availability	Platform supports operational availability.	Legacy target 99.5%, not approved.	TBD
NFR-08	Reliability	Alert pipeline continues even if AI/reporting is slow.	Alerting is prioritized.	PARTIAL
NFR-09	Notification	Notifications are timely.	Legacy: push/in-app < 30 seconds, email < 5 minutes.	TBD
NFR-10	Scalability	System supports many farms/owners with isolation.	Data isolated by farm/owner/scope.	PARTIAL
NFR-11	Offline	Mobile supports basic offline/low-connectivity workflows.	Cache and pending sync; conflict rules TBD.	PARTIAL / PLANNED
NFR-12	Usability	Mobile optimizes field operation.	Fast entry, large controls, outdoor/one-hand usage.	PARTIAL
NFR-13	Auditability	Important actions have audit logs.	Auth, permission, device control, config, closed data edits.	PARTIAL
NFR-14	Data Retention	Retention follows data type requirements.	Retention policy needs approval.	TBD

11. Business Flows

11.1 Global Flow

Login.
Validate credentials/session.
Load role, permissions and farm/pond/ticket scope.
Open dashboard.
Select farm and pond.
Monitor water metrics, device status and farming logs.
If normal, continue monitoring and daily logging.
If alert, acknowledge, take action and close.
If device issue, create/open ticket, assign, process and close.
If help is needed, open handbook/chatbot and create ticket if needed.

11.2 Alert Flow

Sensor/device/user event occurs.
System evaluates rule/threshold.
System creates alert if condition matches.
System sends notification/email where configured.
User opens alert detail and acknowledges.
User adds note, controls device, creates ticket or consults handbook/chatbot.
User updates status.
System logs actions and escalates on timeout/SLA.

11.3 Ticket Flow

User creates ticket with pond/device/description/attachment.
System sends configured notification/email.
Admin or system assigns technical staff.
Technical staff accepts, reviews context, updates progress and resolves.
System records SLA metrics and status notification.

11.4 Chatbot Flow

User opens chatbot and selects pond context where relevant.
System validates permission.
User enters question or uploads image.
Chatbot retrieves approved handbook and permitted pond data.
Chatbot responds with recommendation, confidence and references.
If low-confidence/high-risk, chatbot suggests KTV or ticket.
User rates response or creates ticket.
Conversation is stored according to retention policy.

12. MVP Scope Mapping

Stage	Scope	Status
MVP 1	Auth, role/farm/pond, six-metric dashboard, sensor cadence, basic environmental alerts, device on/off, device history, technical ticket and email.	PARTIAL
MVP 2	Feeding entry, manual pH/alkalinity/minerals/siphon, reports, Excel export, KTV assignment and basic handbook.	PARTIAL
MVP 3	Rule-based energy optimization, device runtime analysis and text chatbot from handbook/pond data.	PARTIAL / PLANNED
MVP 4	AI feeding, feeding-time prediction, growth assessment, PCR/FCR/productivity analysis and image chatbot.	PLANNED
Future Phase	SMS/Zalo/calls, SSO/OAuth, ERP/supply-chain integration, advanced traceability and realtime camera AI.	FUTURE

13. Acceptance Criteria

ID	Criteria	Status
AC-01	Supported roles can log in on web/mobile and see only allowed data/actions.	PARTIAL
AC-02	Admin can create farm, pond, crop, user, assign KTV/sensor/device and configure thresholds.	PARTIAL
AC-03	Pond dashboard shows six metrics, colors, timestamps, sensor status and history chart.	PARTIAL
AC-04	System creates alerts for threshold breach or sensor/device errors and notifies correct recipients.	PARTIAL
AC-05	Authorized users can control devices and command log is complete.	PARTIAL
AC-06	KTV/farm owner can enter feeding, environment, mineral, siphon and productivity data in scope.	PARTIAL
AC-07	Reports filter by farm/pond/time and Excel export does not include unauthorized data.	PARTIAL
AC-08	Users can create tickets with attachments and configured technical email is sent.	PARTIAL
AC-09	Handbook shows approved articles and Admin can manage versions.	PARTIAL
AC-10	Chatbot uses authorized pond data and approved handbook; image analysis is preliminary.	PLANNED
AC-11	Mobile supports notification, quick field entry, device control and basic offline cache/sync.	PARTIAL / PLANNED
AC-12	Critical actions have audit logs.	PARTIAL

14. Assumptions, Dependencies And Constraints

14.1 Assumptions

ID	Assumption	Status
AS-01	Web and mobile both support role-based workflows.	PARTIAL
AS-02	Default water indicators are pH, DO, salinity, algae/ORP, alkalinity and temperature.	TBD
AS-03	Sensor data cadence is around 20 minutes in MVP unless devices support faster updates.	TBD
AS-04	AI supports decisions but does not replace technicians/operators.	CONFIRMED

14.2 Dependencies

ID	Dependency	Status
DEP-01	Sensor/device gateway for data and commands.	PARTIAL
DEP-02	Email provider for reset, ticket, escalation and reports.	PARTIAL
DEP-03	Push notification provider for mobile events.	PARTIAL / TBD
DEP-04	Object storage for media and exported files.	PARTIAL
DEP-05	Approved handbook content for AI chatbot.	PARTIAL
DEP-06	AI/LLM provider and model policy.	PLANNED

14.3 Constraints

Constraint	Impact	Status
Temporary authorization bypasses exist.	Production blocker until fixed/test-covered.	OPEN
Device control is high risk.	Requires permission, logging and fail-safe behavior.	OPEN
PCR/FCR formulas are not approved.	Related reports/AI features cannot be accepted.	OPEN
Offline sync conflict strategy is undefined.	Offline acceptance remains incomplete.	OPEN

15. Open Questions

ID	Question	Owner	Priority
OQ-01	What is the approved PCR/FCR formula?	Domain/Product	Blocker
OQ-02	Should algae be represented as algae, ORP or another indicator?	Domain/Product	High
OQ-03	Are thresholds global, farm-specific, pond-specific, shrimp-type-specific or stage-specific?	Product/Domain	High
OQ-04	Can the system auto-control devices, or must users confirm actions?	Product/Tech	Blocker
OQ-05	How many devices and sensors can each pond support?	Product/Architecture	High
OQ-06	Does production IoT use push or pull?	Product/IoT	High
OQ-07	Who receives technical escalation emails?	Product/Ops	Medium
OQ-08	What is the official productivity measurement method?	Domain/Product	High
OQ-09	What are siphon units and evidence requirements?	Domain/Product	Medium
OQ-10	How are offline sync conflicts resolved?	Product/Mobile	High
OQ-11	Which AI provider, model and knowledge sources are approved?	Product/AI/Security	High
OQ-12	What retention policy applies to telemetry, audit, files and chatbot history?	Security/Ops	High
OQ-13	Should large exports run synchronously or as background jobs?	Product/Backend	High
OQ-14	What production SLA/SLO, RPO and RTO are required?	Product/Ops	High

16. Suggested Screen List

Screen Group	Main Screens	Status
Authentication	Login, Forgot Password, Reset Password, Profile, Session Management.	PARTIAL
Dashboard	System Dashboard, Farm Dashboard, Pond Dashboard, Water Metric Detail.	PARTIAL
Farm/Pond	Farm List, Farm Detail, Pond List, Pond Detail, Crop Detail, Assignment Management.	PARTIAL
Alert	Alert List, Alert Detail, Alert Handling Timeline.	PARTIAL
Device	Device List, Device Detail, Device Control, Auto Rule Configuration, Command History.	PARTIAL
Feeding	Feeding Entry, Feeding History, AI Suggestion, Feeding vs Environment Chart.	PARTIAL / PLANNED
Logs	Manual Environment Entry, Mineral Entry, Siphon Entry, Productivity Entry, Daily Log Summary.	PARTIAL
Reports	Report Center, Report Detail, Export Excel, Scheduled Report Configuration.	PARTIAL / PLANNED
Ticket	Ticket List, Create Ticket, Ticket Detail, SLA Dashboard.	PARTIAL
Handbook	Article Library, Article Detail, Favorite Articles, Article Admin, Article Approval.	PARTIAL
Chatbot	Chat Conversation, Image Upload, Conversation History, Create Ticket from Chat.	PLANNED
Notification	Notification Center, Notification Detail, Notification Preferences.	PARTIAL / PLANNED
Settings	Threshold Settings, Catalog Settings, SLA Settings, Email Template, Chatbot Policy, Service Plan.	PARTIAL / PLANNED

17. Traceability

SRS Area	Current Docs
Business requirements	`02_BRD — Business Requirements Document.md`, `01-product/requirements/business-requirements.md`
Product requirements	`01_PRD — Product Requirements Document.md`, `01-product/PRD.md`
Split SRS entry point	`01-product/SRS.md`
Functional requirements	`01-product/requirements/functional-requirements.md`
Data requirements	`01-product/requirements/data-requirements.md`
Business rules	`01-product/requirements/business-rules.md`
Permissions	`01-product/requirements/permission-matrix.md`, `08-security/access-control.md`
Integrations	`04-architecture/integrations.md`
Acceptance criteria and tests	`01-product/requirements/acceptance-criteria.md`, `06-testing/test-cases.md`
User flow and screens	`03-design/user-flow.md`, `03-design/screen-list.md`
Gaps	`DOCUMENTATION-GAPS.md`

18. Approval

Role	Name	Decision	Date
Product Owner	TBD	TBD	TBD
Engineering Lead	TBD	TBD	TBD
QA Lead	TBD	TBD	TBD
Security/Ops	TBD	TBD	TBD

19. Document History

Version	Date	Author	Changes
1.0	2026-09-16	Product & Engineering	Created complete SRS from legacy SRS, current PRD, BRD and 10-part requirement docs.

End of Software Requirements Specification